<html>
<head>
<title>FreeCC Parser Generator, Version 0.9.1</title>
</head>
<body>
<h1>FreeCC Parser Generator 0.9.1, released 22 October 2008</h1>

<p>This is the second publicly announced release of FreeCC, labelled as version
 0.9.1. Version 0.9 was released on 2 October 2008.
 
<p> Version numbers are quite arbitrary, of course. This one is somewhat 
 misleading as regards the maturity of the tool. FreeCC is based on forking the 
 JavaCC codebase in April of this year, which is basically the same code that was
 released soon afterwards as JavaCC version 4.1. 

<p>Hence, FreeCC version 0.9.x is a more advanced version of the JavaCC tool which 
is labelled 4.x. In fact, if this work had been done as part of the JavaCC project, 
it would be a preview release of JavaCC 5.0. 

<h2>Changes since the last release</h2>

<p>This release introduces a new INCLUDE_GRAMMAR statement that allows you to
organize your grammar in multiple physical files. This is now used in the FreeCC
code itself. See the src/grammars directory for more information.

<p>Various glitches relating to the new BASE_SRC_DIR option have been fixed. The 
NODE_PACKAGE option now works correctly. You can specify a separate NODE_PACKAGE 
in which to generate your AST node files. FreeCC determines the directory
based on the BASE_SRC_DIR option that you specify. The FreeCC codebase itself
uses this and now generates the parser files in the org.visigoths.freecc.parser
package and the node files in the org.visigoths.freecc.parser.tree package. 
 
<p>There have been a large number of bugs and assorted glitches fixed. I am not 
organized enough to keep track of all this systematically and list them.

<h2>Getting Started</h2>

<p>How you would best go about getting started will, I think, depend greatly on 
your level of prior experience using JavaCC specifically, and/or other similar 
sorts of tools. Besides that, it depends on your learning style. 

<h2>If you are new to JavaCC...</h2>

<p>Personally, I began using JavaCC at some point in 2001. At the time, I had 
basically zero experience using this kind of tool. Nonetheless, if memory serves, 
I got going with it fairly quickly. Even though the documentation was extremely 
sparse (and still is) it was fairly easy to get going with it simply by mucking 
about with the simple examples that came with the tool. See the Simple1.jj, 
Simple2.jj, and Simple3.jj that are in the <code>examples/SimpleExamples</code> 
directory. I found that by simply experimenting using these trivial examples 
as a starting point, I was able to expand my knowledge and gain some sense of 
comfort fairly quickly. Oddly enough, even though JavaCC's main competitor, ANTLR, 
has much more documentation, I found that it presented a much steeper learning 
curve.

<p>I believe that the best materials available online for familiarizing yourself 
with JavaCC would be the <a href="http://www.engr.mun.ca/~theo/JavaCC-FAQ/">FAQ</a> 
and <a href="http://www.engr.mun.ca/~theo/JavaCC-Tutorial/">tutorial</a> by 
Theodore Norvell. 

<h2>If you are an experienced user of JavaCC...</h2>

<p>People who are already comfortable using JavaCC should have little trouble 
getting started with FreeCC. In this case, you will be most interested in seeing 
what features FreeCC offers beyond what is in JavaCC. A good starting point is 
this <a href="http://code.google.com/p/freecc/wiki/NewInFreeCC">Wiki page</a>. 
You should certainly have a look at the page on 
<a href="http://code.google.com/p/freecc/wiki/CodeInjection">code injection</a> 
as well as the page that describes 
<a href="http://code.google.com/p/freecc/wiki/TreeBuildingEnhancements">tree 
building enhancements</a> in FreeCC.

<p>Some of the examples have been reworked to show how these new features such 
as code injection can be put to good use. The simplest example to examine 
would be <code>examples/TreeBuildingExamples/eg2.jjt</code>, an example that 
is included with JavaCC, but here, has been rewritten to use code injection. You 
can then move on and look at eg3.jjt and eg4.jjt to see some other, still quite 
simple, examples of how the INJECT_CODE instruction can be used.

<p>A much more involved example of the use of new FreeCC features is in the 
src/grammars directory. This contains a modified version of the Java 1.5 grammar 
included with JavaCC. 

<h2>Please Join the Community</h2>

<p>While there is no obligation, of course, FreeCC users are strongly encouraged 
to subscribe to the freecc-devel mailing list. You can do so 
<a href="http://groups.google.com/group/freecc-devel">here.</a> I am very 
interested in receiving user feedback on this work.

<br>
<br>Jonathan Revusky
<br>Palma de Mallorca, Spain
<br>October 2008
 
</body>
</html>